home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / ubrk.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  12KB  |  324 lines
  1. /*
  2. *****************************************************************************************
  3. *                                                                                       *
  4. * COPYRIGHT:                                                                            *
  5. *   (C) Copyright Taligent, Inc.,  1996                                                 *
  6. *   (C) Copyright International Business Machines Corporation,  1998-1999               *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.                  *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure             *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                              *
  10. *                                                                                       *
  11. *****************************************************************************************
  12. */
  13.  
  14. #ifndef UBRK_H
  15. #define UBRK_H
  16.  
  17. #include "utypes.h"
  18. /**
  19.  * The BreakIterator C API defines  methods for finding the location
  20.  * of boundaries in text. Pointer to a UBreakIterator maintain a 
  21.  * current position and scan over text returning the index of characters 
  22.  * where boundaries occur.
  23.  * <P>
  24.  * Line boundary analysis determines where a text string can be broken
  25.  * when line-wrapping. The mechanism correctly handles punctuation and
  26.  * hyphenated words.
  27.  * <P>
  28.  * Sentence boundary analysis allows selection with correct
  29.  * interpretation of periods within numbers and abbreviations, and
  30.  * trailing punctuation marks such as quotation marks and parentheses.
  31.  * <P>
  32.  * Word boundary analysis is used by search and replace functions, as
  33.  * well as within text editing applications that allow the user to
  34.  * select words with a double click. Word selection provides correct
  35.  * interpretation of punctuation marks within and following
  36.  * words. Characters that are not part of a word, such as symbols or
  37.  * punctuation marks, have word-breaks on both sides.
  38.  * <P>
  39.  * Character boundary analysis allows users to interact with
  40.  * characters as they expect to, for example, when moving the cursor
  41.  * through a text string. Character boundary analysis provides correct
  42.  * navigation of through character strings, regardless of how the
  43.  * character is stored.  For example, an accented character might be
  44.  * stored as a base character and a diacritical mark. What users
  45.  * consider to be a character can differ between languages.
  46.  * <P>
  47.  * This is the interface for all text boundaries.
  48.  * <P>
  49.  * Examples:
  50.  * <P>
  51.  * Helper function to output text
  52.  * <pre>
  53.  * .   void printTextRange(UChar* str, UTextOffset start, UTextOffset end )
  54.  * .   {
  55.  * .        UChar* result;
  56.  * .        UChar* temp;
  57.  * .        const char* res;
  58.  * .        temp=(UChar*)malloc(sizeof(UChar) * ((u_strlen(str)-start)+1));
  59.  * .        result=(UChar*)malloc(sizeof(UChar) * ((end-start)+1));
  60.  * .        u_strcpy(temp, &str[start]);
  61.  * .        u_strncpy(result, temp, end-start);
  62.  * .        res=(char*)malloc(sizeof(char) * (u_strlen(result)+1));
  63.  * .        u_austrcpy(res, result);
  64.  * .        printf("%s\n", res); 
  65.  * .   }
  66.  * </pre>
  67.  * Print each element in order:
  68.  * <pre>
  69.  * .   void printEachForward( UBreakIterator* boundary, UChar* str)
  70.  * .   {
  71.  * .      UTextOffset end;
  72.  * .      UTextOffset start = ubrk_first(boundary);
  73.  * .      for (end = ubrk_next(boundary)); end != UBRK_DONE; start = end, end = ubrk_next(boundary))
  74.  * .        {
  75.  * .            printTextRange(str, start, end );
  76.  * .        }
  77.  * .   }
  78.  * </pre>
  79.  * Print each element in reverse order:
  80.  * <pre>
  81.  * .   void printEachBackward( UBreakIterator* boundary, UChar* str)
  82.  * .   {
  83.  * .      UTextOffset start;
  84.  * .      UTextOffset end = ubrk_last(boundary);
  85.  * .      for (start = ubrk_previous(boundary); start != UBRK_DONE;  end = start, start =ubrk_previous(boundary))
  86.  * .        {
  87.  * .            printTextRange( str, start, end );
  88.  * .        }
  89.  * .   }
  90.  * </pre>
  91.  * Print first element
  92.  * <pre>
  93.  * .   void printFirst(UBreakIterator* boundary, UChar* str)
  94.  * .   {
  95.  * .       UTextOffset end;
  96.  * .       UTextOffset start = ubrk_first(boundary);
  97.  * .       end = ubrk_next(boundary);
  98.  * .       printTextRange( str, start, end );
  99.  * .   }
  100.  * </pre>
  101.  * Print last element
  102.  * <pre>
  103.  * .   void printLast(UBreakIterator* boundary, UChar* str)
  104.  * .   {
  105.  * .       UTextOffset start;
  106.  * .       UTextOffset end = ubrk_last(boundary);
  107.  * .       start = ubrk_previous(boundary);
  108.  * .       printTextRange(str, start, end );
  109.  * .   }
  110.  * </pre>
  111.  * Print the element at a specified position
  112.  * <pre>
  113.  * .   void printAt(UBreakIterator* boundary, UTextOffset pos , UChar* str)
  114.  * .   {
  115.  * .       UTextOffset start;
  116.  * .       UTextOffset end = ubrk_following(boundary, pos);
  117.  * .       start = ubrk_previous(boundary);
  118.  * .       printTextRange(str, start, end );
  119.  * .   }
  120.  * </pre>
  121.  * Creating and using text boundaries
  122.  * <pre>
  123.  * .      void BreakIterator_Example( void )
  124.  * .      {
  125.  * .          UBreakIterator* boundary;
  126.  * .          UChar *stringToExamine;
  127.  * .          stringToExamine=(UChar*)malloc(sizeof(UChar) * (strlen("Aaa bbb ccc. Ddd eee fff.")+1) );
  128.  * .          u_uastrcpy(stringToExamine, "Aaa bbb ccc. Ddd eee fff.");
  129.  * .          printf("Examining: "Aaa bbb ccc. Ddd eee fff.");
  130.  * .
  131.  * .          //print each sentence in forward and reverse order
  132.  * .          boundary = ubrk_open(UBRK_SENTENCE, "en_us", stringToExamine, u_strlen(stringToExamine), &status);
  133.  * .          printf("----- forward: -----------\n"); 
  134.  * .          printEachForward(boundary, stringToExamine);
  135.  * .          printf("----- backward: ----------\n");
  136.  * .          printEachBackward(boundary, stringToExamine);
  137.  * .          ubrk_close(boundary);
  138.  * .
  139.  * .          //print each word in order
  140.  * .          boundary = ubrk_open(UBRK_WORD, "en_us", stringToExamine, u_strlen(stringToExamine), &status);
  141.  * .          printf("----- forward: -----------\n"); 
  142.  * .          printEachForward(boundary, stringToExamine);
  143.  * .          printf("----- backward: ----------\n");
  144.  * .          printEachBackward(boundary, stringToExamine);
  145.  * .          //print first element
  146.  * .          printf("----- first: -------------\n");
  147.  * .          printFirst(boundary, stringToExamine);
  148.  * .          //print last element
  149.  * .          printf("----- last: --------------\n");
  150.  * .          printLast(boundary, stringToExamine);
  151.  * .          //print word at charpos 10
  152.  * .          printf("----- at pos 10: ---------\n");
  153.  * .          printAt(boundary, 10 , stringToExamine);
  154.  * .
  155.  * .          ubrk_close(boundary);
  156.  * .      }
  157.  * </pre>
  158.  */
  159. /** A text-break iterator */
  160. typedef void* UBreakIterator;
  161.  
  162. /** The possible types of text boundaries. */
  163. enum UBreakIteratorType {
  164.   /** Character breaks */
  165.   UBRK_CHARACTER,
  166.   /** Word breaks */
  167.   UBRK_WORD,
  168.   /** Line breaks */
  169.   UBRK_LINE,
  170.   /** Sentence breaks */
  171.   UBRK_SENTENCE
  172. };
  173. typedef enum UBreakIteratorType UBreakIteratorType;
  174.  
  175. /** Value indicating all text boundaries have been returned. */
  176. #define UBRK_DONE ((UTextOffset) -1)
  177.  
  178. /**
  179.  * Open a new UBreakIterator for locating text boundaries for a specified locale.
  180.  * A UBreakIterator may be used for detecting character, line, word, 
  181.  * and sentence breaks in text.
  182.  * @param type The type of UBreakIterator to open: one of UBRK_CHARACTER, UBRK_WORD,
  183.  * UBRK_LINE, UBRK_SENTENCE
  184.  * @param locale The locale specifying the text-breaking conventions.
  185.  * @param text The text to be iterated over.
  186.  * @param textLength The number of characters in text, or -1 if null-terminated.
  187.  * @param status A UErrorCode to receive any errors.
  188.  * @return A UBreakIterator for the specified locale.
  189.  * @see ubrk_openRules
  190.  */
  191. U_CAPI UBreakIterator*
  192. ubrk_open(UBreakIteratorType type,
  193.       const char *locale,
  194.       const UChar *text,
  195.       int32_t textLength,
  196.       UErrorCode *status);
  197.  
  198. /**
  199.  * Open a new UBreakIterator for locating text boundaries using specified breaking rules.
  200.  * The rule syntax is ... (TBD)
  201.  * @param rules A set of rules specifying the text breaking conventions.
  202.  * @param rulesLength The number of characters in rules, or -1 if null-terminated.
  203.  * @param text The text to be iterated over.
  204.  * @param textLength The number of characters in text, or -1 if null-terminated.
  205.  * @param status A UErrorCode to receive any errors.
  206.  * @return A UBreakIterator for the specified rules.
  207.  * @see ubrk_open
  208.  */
  209. U_CAPI UBreakIterator*
  210. ubrk_openRules(const UChar *rules,
  211.            int32_t rulesLength,
  212.            const UChar *text,
  213.            int32_t textLength,
  214.            UErrorCode *status);
  215.  
  216. /**
  217. * Close a UBreakIterator.
  218. * Once closed, a UBreakIterator may no longer be used.
  219. * @param bi The break iterator to close.
  220. */
  221. U_CAPI void
  222. ubrk_close(UBreakIterator *bi);
  223.  
  224. /**
  225.  * Determine the most recently-returned text boundary.
  226.  * 
  227.  * @param bi The break iterator to use.
  228.  * @return The character index most recently returned by \Ref{ubrk_next}, \Ref{ubrk_previous}, 
  229.  * \Ref{ubrk_first}, or \Ref{ubrk_last}.
  230.  */
  231. U_CAPI UTextOffset
  232. ubrk_current(const UBreakIterator *bi);
  233.  
  234. /**
  235.  * Determine the text boundary following the current text boundary.
  236.  * 
  237.  * @param bi The break iterator to use.
  238.  * @return The character index of the next text boundary, or UBRK_DONE
  239.  * if all text boundaries have been returned.
  240.  * @see ubrk_previous
  241.  */
  242. U_CAPI UTextOffset
  243. ubrk_next(UBreakIterator *bi);
  244.  
  245. /**
  246.  * Determine the text boundary preceding the current text boundary.
  247.  *
  248.  * @param bi The break iterator to use.
  249.  * @return The character index of the preceding text boundary, or UBRK_DONE
  250.  * if all text boundaries have been returned.
  251.  * @see ubrk_next
  252.  */
  253. U_CAPI UTextOffset
  254. ubrk_previous(UBreakIterator *bi);
  255.  
  256. /**
  257.  * Determine the index of the first character in the text being scanned.
  258.  * This is not always the same as index 0 of the text.
  259.  * @param bi The break iterator to use.
  260.  * @return The character index of the first character in the text being scanned.
  261.  * @see ubrk_last
  262.  */
  263. U_CAPI UTextOffset
  264. ubrk_first(UBreakIterator *bi);
  265.  
  266. /**
  267.  * Determine the index immediately <EM>beyond</EM> the last character in the text being
  268.  * scanned.
  269.  * This is not the same as the last character.
  270.  * @param bi The break iterator to use.
  271.  * @return The character offset immediately <EM>beyond</EM> the last character in the
  272.  * text being scanned.
  273.  * @see ubrk_first
  274.  */
  275. U_CAPI UTextOffset
  276. ubrk_last(UBreakIterator *bi);
  277.  
  278. /**
  279.  * Determine the text boundary preceding the specified offset.
  280.  * The value returned is always smaller than offset, or UBRK_DONE.
  281.  * @param bi The break iterator to use.
  282.  * @param offset The offset to begin scanning.
  283.  * @return The text boundary preceding offset, or UBRK_DONE.
  284.  * @see ubrk_following
  285.  */
  286. U_CAPI UTextOffset
  287. ubrk_preceding(UBreakIterator *bi,
  288.            UTextOffset offset);
  289.  
  290. /**
  291.  * Determine the text boundary following the specified offset.
  292.  * The value returned is always greater than offset, or UBRK_DONE.
  293.  * @param bi The break iterator to use.
  294.  * @param offset The offset to begin scanning.
  295.  * @return The text boundary following offset, or UBRK_DONE.
  296.  * @see ubrk_preceding
  297.  */
  298. U_CAPI UTextOffset
  299. ubrk_following(UBreakIterator *bi,
  300.            UTextOffset offset);
  301.  
  302. /**
  303. * Get a locale for which text breaking information is available.
  304. * A UBreakIterator in a locale returned by this function will perform the correct
  305. * text breaking for the locale.
  306. * @param index The index of the desired locale.
  307. * @return A locale for which number text breaking information is available, or 0 if none.
  308. * @see ubrk_countAvailable
  309. */
  310. U_CAPI const char*
  311. ubrk_getAvailable(int32_t index);
  312.  
  313. /**
  314. * Determine how many locales have text breaking information available.
  315. * This function is most useful as determining the loop ending condition for
  316. * calls to \Ref{ubrk_getAvailable}.
  317. * @return The number of locales for which text breaking information is available.
  318. * @see ubrk_getAvailable
  319. */
  320. U_CAPI int32_t
  321. ubrk_countAvailable(void);
  322.  
  323. #endif
  324.